Problem

The current ContextExtension implementation uses Scala's default scala.collection.Map, which only preserves insertion order for up to 4 elements (using specialized Map1 through Map4 implementations). For larger maps, the traversal order is not guaranteed and may change across Scala versions, which is problematic for consensus-critical code where insertion order matters.

Solution

Implemented SigmaMap[V], a new immutable map data structure specifically designed for Byte keys that:

1. Preserves Insertion Order: Uses a Vector[Byte] to maintain insertion order and a Map[Byte, V] for O(1) lookups
2. Handles Full Byte Range: Correctly handles all 256 possible byte values (-128 to 127)
3. Consensus-Safe: Deterministic behavior independent of Scala version
4. Immutable: All operations return new instances, preventing accidental mutations
5. Efficient: O(1) lookups via internal Map, O(1) updates for existing keys
6. Translation-Ready: Simple design that can be easily ported to JavaScript and Rust

Implementation Details

Core Data Structure:

• insertionOrder: Vector[Byte] - maintains the order keys were inserted
• values: Map[Byte, V] - provides fast lookups

Key Operations:

• updated(key, value): Adds/updates entries while preserving insertion order
• removed(key): Removes entries while maintaining order of remaining elements
• get(key): O(1) lookup
• iterator: Returns elements in insertion order
• filter: Filters while preserving order

Testing

Comprehensive test suite (SigmaMapSpec) includes:

• Basic operations (empty, single element, get, contains)
• Insertion order preservation for arbitrary sequences
• Order preservation when updating existing keys
• Order preservation after removals
• Full Byte range coverage (-128 to 127)
• All 256 possible byte values handled correctly
• Property-based tests with ScalaCheck
• Complex scenarios with mixed operations
• Comparison with scala.collection.Map behavior for >4 elements
• Equality and hashCode consistency

Files Changed

Added:

• ergo-core/src/main/scala/org/ergoplatform/utils/SigmaMap.scala - Main implementation
• ergo-core/src/test/scala/org/ergoplatform/utils/SigmaMapSpec.scala - Comprehensive tests

Testing Commands

sbt "project ergoCore" "testOnly org.ergoplatform.utils.SigmaMapSpec"